feat: parse Q10 archived map packets - #936

when this kind of map packet is received, how many of these other fields are also included?

What i'm wondering is if a historical trace kind has a lot of overlap with other fields in Q10MapPacket or if it needs to be a separate type. basically as more fields are added the map packet seems like a sparse object. You could imagine each kind Q10MapPacketKind has a separate dataclass for example, if the overlap is low.

re-reading the code I don't actually see the historical trace even being used anywhere yet, except in the tests.

Naively, it seems to me like we shouldn't be sticking this on to a map package and instead just using the kind to parse a clean record?

How about we get the kind once:

No need to make the second arg optional given we're updating all the callers in this change i believe.

Whats the relationship between a Q10MapPacket and a trace? especially Q10HistoricalTracePacket.

My impression is Q10HistoricalTracePacket is a field that was added to Q10MapPacket, so why would it also be passed here as trace?

we just ignore the second return value, so can it be removed?

re-reading the code I don't actually see the historical trace even being used anywhere yet, except in the tests.

Naively, it seems to me like we shouldn't be sticking this on to a map package and instead just using the kind to parse a clean record?

Because this inherits from RoborockEnum, RoborockEnum._missing_ expects an unknown member (e.g. unknown = -1). Without it, _missing_ defaults to next(item for item in cls), which silently resolves unknown future wire markers to CURRENT = 1.

Also, rather than iterating all members with next((kind for kind in cls ...)) on every push, we can do an O(1) lookup:

class Q10MapPacketKind(RoborockEnum):
    """Semantic kind identified by a Q10 map packet's two-byte marker."""

    unknown = -1
    CURRENT = 1
    TRACE = 2
    CLEAN_RECORD_DETAIL = 3
    SAVED_MAP_DETAIL = 4

    @property
    def marker(self) -> bytes:
        """Return the two-byte wire marker for this packet kind."""
        if self is self.unknown:
            return b""
        return bytes((self.value, 1))

    @classmethod
    def from_payload(cls, payload: bytes) -> "Q10MapPacketKind | None":
        """Return the recognized kind for a payload marker."""
        if len(payload) < 2 or payload[1] != 1:
            return None
        kind = cls(payload[0])
        return None if kind is cls.unknown else kind

(Or if this enum is strictly an internal framing marker classifier, a standard IntEnum without RoborockEnum would avoid the fallback behavior altogether).

Seeing **vars(packet) in parse_map_packet and test_b01_q10_render.py, along with isinstance(packet, Q10CleanRecordMapPacket) in render_q10_map, makes me wonder if subclassing Q10MapPacket is the right abstraction.

A clean-record response isn't really a specialized variant of a map raster; it's a compound payload containing both a map and a historical path. If we model it via composition instead:

@dataclass
class Q10CleanRecordDetail:
    map: Q10MapPacket
    trace: Q10HistoricalTracePacket | None = None

Then:

1. Q10MapPacket remains pure and uniform across all map kinds (avoiding **vars(packet) or duplicating 9 constructor arguments).
2. render_q10_map(packet, trace=None) remains pure and consumer-agnostic—callers just do render_q10_map(record.map, trace=record.trace) with zero isinstance branching or ignored arguments.

Do we need to expose version and opaque_value on the public dataclass?

version is already validated to equal 1 by the parser (returning None otherwise), and opaque_value is undecoded wire framing. Removing them keeps the public domain model clean and aligned with Q10TracePacket.

Can we prune is_clean_record_map_packet and is_saved_map_packet? Since decode_message now checks Q10MapPacketKind.from_payload(payload) directly, these single-expression helpers aren't used in production code.

Similarly, _parse_carpet_mask at line 711 appears to be an unused private compatibility helper that can be cleaned up.

Should we run points = _drop_stray_leading_point(points) here as well?

If clean-record paths share the same firmware sentinel near (0, 0) that live traces have, leaving it in will cause visual lines to the origin and skew solve_q10_calibration.

This line illustrates the friction with subclassing: render_q10_map takes trace: Q10TracePacket | None = None, but if packet is a Q10CleanRecordMapPacket, the passed trace argument is silently ignored.

If we use composition (Q10CleanRecordDetail(map=..., trace=...)), render_q10_map doesn't need this branch at all—the caller simply passes render_q10_map(record.map, trace=record.trace).